home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / perl5 / XML / LibXSLT.pm < prev    next >
Encoding:
Perl POD Document  |  2009-10-07  |  27.3 KB  |  1,009 lines

  1. # $Id: LibXSLT.pm 228 2009-10-07 12:25:23Z pajas $
  2. #
  3. # This is free software, you may use it and distribute it under the same terms as
  4. # Perl itself.
  5. #
  6. # Copyright 2001-2009 AxKit.com Ltd.
  7. #
  8. #
  9. package XML::LibXSLT;
  10.  
  11. use strict;
  12. use vars qw($VERSION @ISA $USE_LIBXML_DATA_TYPES $MatchCB $ReadCB $OpenCB $CloseCB);
  13.  
  14. sub REQUIRE_XML_LIBXML_ABI_VERSION { 2 }
  15.  
  16. use XML::LibXML 1.70;
  17. use XML::LibXML::Literal;
  18. use XML::LibXML::Boolean;
  19. use XML::LibXML::Number;
  20. use XML::LibXML::NodeList;
  21.  
  22.  
  23. BEGIN {
  24. use Carp;
  25.  
  26. require Exporter;
  27.  
  28. $VERSION = "1.70";
  29.  
  30. require DynaLoader;
  31.  
  32. @ISA = qw(DynaLoader);
  33.  
  34. # avoid possible shared library name conflict on Win32
  35. # not using this trick on 5.10.0 (suffering from DynaLoader bug)
  36. local $DynaLoader::dl_dlext = "xs.$DynaLoader::dl_dlext" if (($^O eq 'MSWin32') && ($] ne '5.010000'));
  37.  
  38. bootstrap XML::LibXSLT $VERSION;
  39.  
  40. # the following magic lets XML::LibXSLT internals know
  41. # where to register XML::LibXML proxy nodes
  42. INIT_THREAD_SUPPORT() if XML::LibXML::threads_shared_enabled();
  43. $USE_LIBXML_DATA_TYPES = 0;
  44. }
  45.  
  46.  
  47. sub new {
  48.     my $class = shift;
  49.     my %options = @_;
  50.     my $self = bless \%options, $class;
  51.     return $self;
  52. }
  53.  
  54. # ido - perl dispatcher
  55. sub perl_dispatcher {
  56.     my $func = shift;
  57.     my @params = @_;
  58.     my @perlParams;
  59.     
  60.     my $i = 0;
  61.     while (@params) {
  62.         my $type = shift(@params);
  63.         if ($type eq 'XML::LibXML::Literal' or 
  64.             $type eq 'XML::LibXML::Number' or
  65.             $type eq 'XML::LibXML::Boolean')
  66.         {
  67.             my $val = shift(@params);
  68.             unshift(@perlParams, $USE_LIBXML_DATA_TYPES ? $type->new($val) : $val);
  69.         }
  70.         elsif ($type eq 'XML::LibXML::NodeList') {
  71.             my $node_count = shift(@params);
  72.             my @nodes = splice(@params, 0, $node_count);
  73.             # warn($_->getName) for @nodes;
  74.             unshift(@perlParams, $type->new(@nodes));
  75.         }
  76.     }
  77.     
  78.     $func = "main::$func" unless ref($func) || $func =~ /(.+)::/;
  79.     no strict 'refs';
  80.     my $res = $func->(@perlParams);
  81.     return $res;
  82. }
  83.  
  84.  
  85. sub xpath_to_string {
  86.     my @results;
  87.     while (@_) {
  88.         my $value = shift(@_); $value = '' unless defined $value;
  89.         push @results, $value;
  90.         if (@results % 2) {
  91.             # key
  92.             $results[-1] =~ s/:/_/g; # XSLT doesn't like names with colons
  93.         }
  94.         else {
  95.             if ($value =~ s/'/', "'", '/g) {
  96.             $results[-1] = "concat('$value')";
  97.             }
  98.             else {
  99.                 $results[-1] = "'$results[-1]'";
  100.             }
  101.         }
  102.     }
  103.     return @results;
  104. }
  105.  
  106. #-------------------------------------------------------------------------#
  107. # callback functions                                                      #
  108. #-------------------------------------------------------------------------#
  109.  
  110. sub security_callbacks {
  111.    my $self = shift;
  112.    my $scbclass = shift;
  113.  
  114.    if ( defined $scbclass ) {
  115.       $self->{XML_LIBXSLT_SECPREFS} = $scbclass;
  116.    }
  117.    return $self->{XML_LIBXSLT_SECPREFS};
  118. }
  119.  
  120. sub input_callbacks {
  121.     my $self = shift;
  122.     my $icbclass = shift;
  123.  
  124.     if ( defined $icbclass ) {
  125.         $self->{XML_LIBXSLT_CALLBACK_STACK} = $icbclass;
  126.     }
  127.     return $self->{XML_LIBXSLT_CALLBACK_STACK};
  128. }
  129.  
  130. sub match_callback {
  131.     my $self = shift;
  132.     if ( ref $self ) {
  133.         if ( scalar @_ ) {
  134.             $self->{XML_LIBXSLT_MATCH_CB} = shift;
  135.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  136.         }
  137.         return $self->{XML_LIBXSLT_MATCH_CB};
  138.     }
  139.     else {
  140.         $MatchCB = shift if scalar @_;
  141.         return $MatchCB;
  142.     }
  143. }
  144.  
  145. sub read_callback {
  146.     my $self = shift;
  147.     if ( ref $self ) {
  148.         if ( scalar @_ ) {
  149.             $self->{XML_LIBXSLT_READ_CB} = shift;
  150.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  151.         }
  152.         return $self->{XML_LIBXSLT_READ_CB};
  153.     }
  154.     else {
  155.         $ReadCB = shift if scalar @_;
  156.         return $ReadCB;
  157.     }
  158. }
  159.  
  160. sub close_callback {
  161.     my $self = shift;
  162.     if ( ref $self ) {
  163.         if ( scalar @_ ) {
  164.             $self->{XML_LIBXSLT_CLOSE_CB} = shift;
  165.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  166.         }
  167.         return $self->{XML_LIBXSLT_CLOSE_CB};
  168.     }
  169.     else {
  170.         $CloseCB = shift if scalar @_;
  171.         return $CloseCB;
  172.     }
  173. }
  174.  
  175. sub open_callback {
  176.     my $self = shift;
  177.     if ( ref $self ) {
  178.         if ( scalar @_ ) {
  179.             $self->{XML_LIBXSLT_OPEN_CB} = shift;
  180.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  181.         }
  182.         return $self->{XML_LIBXSLT_OPEN_CB};
  183.     }
  184.     else {
  185.         $OpenCB = shift if scalar @_;
  186.         return $OpenCB;
  187.     }
  188. }
  189.  
  190. sub callbacks {
  191.     my $self = shift;
  192.     if ( ref $self ) {
  193.         if (@_) {
  194.             my ($match, $open, $read, $close) = @_;
  195.             @{$self}{qw(XML_LIBXSLT_MATCH_CB XML_LIBXSLT_OPEN_CB XML_LIBXSLT_READ_CB XML_LIBXSLT_CLOSE_CB)} = ($match, $open, $read, $close);
  196.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  197.         }
  198.         else {
  199.             return @{$self}{qw(XML_LIBXSLT_MATCH_CB XML_LIBXSLT_OPEN_CB XML_LIBXSLT_READ_CB XML_LIBXSLT_CLOSE_CB)};
  200.         }
  201.     }
  202.     else {
  203.         if (@_) {
  204.             ( $MatchCB, $OpenCB, $ReadCB, $CloseCB ) = @_;
  205.         }
  206.         else {
  207.             return ( $MatchCB, $OpenCB, $ReadCB, $CloseCB );
  208.         }
  209.     }
  210. }
  211.  
  212. sub _init_callbacks{
  213.     my $self = shift;
  214.     my $icb = $self->{XML_LIBXSLT_CALLBACK_STACK};
  215.  
  216.     unless ( defined $icb ) {
  217.         $self->{XML_LIBXSLT_CALLBACK_STACK} = XML::LibXML::InputCallback->new();
  218.         $icb = $self->{XML_LIBXSLT_CALLBACK_STACK};
  219.     }
  220.  
  221.     my $mcb = $self->match_callback();
  222.     my $ocb = $self->open_callback();
  223.     my $rcb = $self->read_callback();
  224.     my $ccb = $self->close_callback();
  225.  
  226.     if ( defined $mcb and defined $ocb and defined $rcb and defined $ccb ) {
  227.         $icb->register_callbacks( [$mcb, $ocb, $rcb, $ccb] );
  228.     }
  229.  
  230.     $self->lib_init_callbacks();
  231.     $icb->init_callbacks();
  232. }
  233.  
  234. sub _cleanup_callbacks {
  235.     my $self = shift;
  236.     $self->{XML_LIBXSLT_CALLBACK_STACK}->cleanup_callbacks();
  237.     my $mcb = $self->match_callback();
  238.     if ( defined $mcb ) {
  239.         $self->{XML_LIBXSLT_CALLBACK_STACK}->unregister_callbacks( [$mcb] );
  240.     }
  241. }
  242.  
  243. sub parse_stylesheet {
  244.     my $self = shift;
  245.  
  246.     $self->_init_callbacks();
  247.  
  248.     my $stylesheet;
  249.     eval { $stylesheet = $self->_parse_stylesheet(@_); };
  250.  
  251.     $self->_cleanup_callbacks();
  252.  
  253.     my $err = $@;
  254.     if ($err) {
  255.         croak $err;
  256.     }
  257.  
  258.     my $rv = {
  259.                XML_LIBXSLT_STYLESHEET => $stylesheet,
  260.                XML_LIBXSLT_CALLBACK_STACK => $self->{XML_LIBXSLT_CALLBACK_STACK},
  261.                XML_LIBXSLT_MATCH_CB => $self->{XML_LIBXSLT_MATCH_CB},
  262.                XML_LIBXSLT_OPEN_CB => $self->{XML_LIBXSLT_OPEN_CB},
  263.                XML_LIBXSLT_READ_CB => $self->{XML_LIBXSLT_READ_CB},
  264.                XML_LIBXSLT_CLOSE_CB => $self->{XML_LIBXSLT_CLOSE_CB},
  265.                XML_LIBXSLT_SECPREFS => $self->{XML_LIBXSLT_SECPREFS},
  266.              };
  267.  
  268.     return bless $rv, "XML::LibXSLT::StylesheetWrapper";
  269. }
  270.  
  271. sub parse_stylesheet_file {
  272.     my $self = shift;
  273.  
  274.     $self->_init_callbacks();
  275.  
  276.     my $stylesheet;
  277.     eval { $stylesheet = $self->_parse_stylesheet_file(@_); };
  278.  
  279.     $self->_cleanup_callbacks();
  280.  
  281.     my $err = $@;
  282.     if ($err) {
  283.         croak $err;
  284.     }
  285.  
  286.     my $rv = {
  287.                XML_LIBXSLT_STYLESHEET => $stylesheet,
  288.                XML_LIBXSLT_CALLBACK_STACK => $self->{XML_LIBXSLT_CALLBACK_STACK},
  289.                XML_LIBXSLT_MATCH_CB => $self->{XML_LIBXSLT_MATCH_CB},
  290.                XML_LIBXSLT_OPEN_CB => $self->{XML_LIBXSLT_OPEN_CB},
  291.                XML_LIBXSLT_READ_CB => $self->{XML_LIBXSLT_READ_CB},
  292.                XML_LIBXSLT_CLOSE_CB => $self->{XML_LIBXSLT_CLOSE_CB},
  293.                XML_LIBXSLT_SECPREFS => $self->{XML_LIBXSLT_SECPREFS},
  294.              };
  295.  
  296.     return bless $rv, "XML::LibXSLT::StylesheetWrapper";
  297. }
  298.  
  299. sub register_xslt_module {
  300.     my $self = shift;
  301.     my $module = shift;
  302.     # Not implemented
  303. }
  304.  
  305. 1;
  306.  
  307. package XML::LibXSLT::StylesheetWrapper;
  308.  
  309. use strict;
  310. use vars qw($MatchCB $ReadCB $OpenCB $CloseCB);
  311.  
  312. use XML::LibXML;
  313. use Carp;
  314.  
  315. sub security_callbacks {
  316.    my $self = shift;
  317.    my $scbclass = shift;
  318.  
  319.    if ( defined $scbclass ) {
  320.       $self->{XML_LIBXSLT_SECPREFS} = $scbclass;
  321.    }
  322.    return $self->{XML_LIBXSLT_SECPREFS};
  323. }
  324.  
  325. sub input_callbacks {
  326.     my $self     = shift;
  327.     my $icbclass = shift;
  328.  
  329.     if ( defined $icbclass ) {
  330.         $self->{XML_LIBXSLT_CALLBACK_STACK} = $icbclass;
  331.     }
  332.     return $self->{XML_LIBXSLT_CALLBACK_STACK};
  333. }
  334.  
  335. sub match_callback {
  336.     my $self = shift;
  337.     if ( ref $self ) {
  338.         if ( scalar @_ ) {
  339.             $self->{XML_LIBXSLT_MATCH_CB} = shift;
  340.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  341.         }
  342.         return $self->{XML_LIBXSLT_MATCH_CB};
  343.     }
  344.     else {
  345.         $MatchCB = shift if scalar @_;
  346.         return $MatchCB;
  347.     }
  348. }
  349.  
  350. sub read_callback {
  351.     my $self = shift;
  352.     if ( ref $self ) {
  353.         if ( scalar @_ ) {
  354.             $self->{XML_LIBXSLT_READ_CB} = shift;
  355.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  356.         }
  357.         return $self->{XML_LIBXSLT_READ_CB};
  358.     }
  359.     else {
  360.         $ReadCB = shift if scalar @_;
  361.         return $ReadCB;
  362.     }
  363. }
  364.  
  365. sub close_callback {
  366.     my $self = shift;
  367.     if ( ref $self ) {
  368.         if ( scalar @_ ) {
  369.             $self->{XML_LIBXSLT_CLOSE_CB} = shift;
  370.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  371.         }
  372.         return $self->{XML_LIBXSLT_CLOSE_CB};
  373.     }
  374.     else {
  375.         $CloseCB = shift if scalar @_;
  376.         return $CloseCB;
  377.     }
  378. }
  379.  
  380. sub open_callback {
  381.     my $self = shift;
  382.     if ( ref $self ) {
  383.         if ( scalar @_ ) {
  384.             $self->{XML_LIBXSLT_OPEN_CB} = shift;
  385.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  386.         }
  387.         return $self->{XML_LIBXSLT_OPEN_CB};
  388.     }
  389.     else {
  390.         $OpenCB = shift if scalar @_;
  391.         return $OpenCB;
  392.     }
  393. }
  394.  
  395. sub callbacks {
  396.     my $self = shift;
  397.     if ( ref $self ) {
  398.         if (@_) {
  399.             my ($match, $open, $read, $close) = @_;
  400.             @{$self}{qw(XML_LIBXSLT_MATCH_CB XML_LIBXSLT_OPEN_CB XML_LIBXSLT_READ_CB XML_LIBXSLT_CLOSE_CB)} = ($match, $open, $read, $close);
  401.             $self->{XML_LIBXSLT_CALLBACK_STACK} = undef;
  402.         }
  403.         else {
  404.             return @{$self}{qw(XML_LIBXSLT_MATCH_CB XML_LIBXSLT_OPEN_CB XML_LIBXSLT_READ_CB XML_LIBXSLT_CLOSE_CB)};
  405.         }
  406.     }
  407.     else {
  408.         if (@_) {
  409.             ( $MatchCB, $OpenCB, $ReadCB, $CloseCB ) = @_;
  410.         }
  411.         else {
  412.             return ( $MatchCB, $OpenCB, $ReadCB, $CloseCB );
  413.         }
  414.     }
  415. }
  416.  
  417. sub _init_callbacks {
  418.     my $self = shift;
  419.     my $icb = $self->{XML_LIBXSLT_CALLBACK_STACK};
  420.  
  421.     unless ( defined $icb ) {
  422.         $self->{XML_LIBXSLT_CALLBACK_STACK} = XML::LibXML::InputCallback->new();
  423.         $icb = $self->{XML_LIBXSLT_CALLBACK_STACK};
  424.     }
  425.  
  426.     my $mcb = $self->match_callback();
  427.     my $ocb = $self->open_callback();
  428.     my $rcb = $self->read_callback();
  429.     my $ccb = $self->close_callback();
  430.  
  431.     if ( defined $mcb and defined $ocb and defined $rcb and defined $ccb ) {
  432.         $icb->register_callbacks( [$mcb, $ocb, $rcb, $ccb] );
  433.     }
  434.     $self->XML::LibXSLT::lib_init_callbacks();
  435.     $icb->init_callbacks();
  436.  
  437.     my $scb = $self->{XML_LIBXSLT_SECPREFS};
  438.     if ( $scb ) {
  439.        $scb->init_callbacks();
  440.     }
  441. }
  442.  
  443. sub _cleanup_callbacks {
  444.     my $self = shift;
  445.     $self->{XML_LIBXSLT_CALLBACK_STACK}->cleanup_callbacks();
  446.     my $mcb = $self->match_callback();
  447.     if ( defined $mcb ) {
  448.         $self->{XML_LIBXSLT_CALLBACK_STACK}->unregister_callbacks( [$mcb] );
  449.     }
  450.  
  451.     my $scb = $self->{XML_LIBXSLT_SECPREFS};
  452.     if ( $scb ) {
  453.        $scb->cleanup_callbacks();
  454.     }
  455. }
  456.  
  457. sub transform {
  458.     my $self = shift;
  459.     my $doc;
  460.  
  461.     $self->_init_callbacks();
  462.     eval { $doc = $self->{XML_LIBXSLT_STYLESHEET}->transform($self,@_); };
  463.     $self->_cleanup_callbacks();
  464.  
  465.     my $err = $@;
  466.     if ($err) {
  467.         croak $err;
  468.     }
  469.  
  470.     return $doc;
  471. }
  472.  
  473. sub transform_file {
  474.     my $self = shift;
  475.     my $doc;
  476.  
  477.     $self->_init_callbacks();
  478.     eval { $doc = $self->{XML_LIBXSLT_STYLESHEET}->transform_file($self,@_); };
  479.     $self->_cleanup_callbacks();
  480.  
  481.     my $err = $@;
  482.     if ($err) {
  483.         croak $err;
  484.     }
  485.  
  486.     return $doc;
  487. }
  488.  
  489. sub output_string { shift->{XML_LIBXSLT_STYLESHEET}->_output_string($_[0],0) }
  490. sub output_as_bytes { shift->{XML_LIBXSLT_STYLESHEET}->_output_string($_[0],1) }
  491. sub output_as_chars { shift->{XML_LIBXSLT_STYLESHEET}->_output_string($_[0],2) }
  492. sub output_fh { shift->{XML_LIBXSLT_STYLESHEET}->output_fh(@_) }
  493. sub output_file { shift->{XML_LIBXSLT_STYLESHEET}->output_file(@_) }
  494. sub media_type { shift->{XML_LIBXSLT_STYLESHEET}->media_type(@_) }
  495. sub output_encoding { shift->{XML_LIBXSLT_STYLESHEET}->output_encoding(@_) }
  496.  
  497. 1;
  498.  
  499. # XML::LibXSLT::Security Interface                                        #
  500. #-------------------------------------------------------------------------#
  501. package XML::LibXSLT::Security;
  502.  
  503. use strict;
  504. use Carp;
  505.  
  506. use vars qw(%OPTION_MAP %_GLOBAL_CALLBACKS);
  507.  
  508. # Maps the option names used in the perl interface to the numeric values
  509. # used by libxslt.
  510. my %OPTION_MAP = (
  511.    read_file  => 1,
  512.    write_file => 2,
  513.    create_dir => 3,
  514.    read_net   => 4,
  515.    write_net  => 5,
  516. );
  517.  
  518. %_GLOBAL_CALLBACKS = ();
  519.  
  520.  
  521. #-------------------------------------------------------------------------#
  522. # global callback                                                         #
  523. #-------------------------------------------------------------------------#
  524. sub _security_check {
  525.     my $option = shift;
  526.     my $retval = 1;
  527.  
  528.     if ($option == 3) {
  529.        $retval = 0;             # Default create_dir to no access
  530.     }
  531.  
  532.     if (exists $_GLOBAL_CALLBACKS{$option}) {
  533.        $retval = $_GLOBAL_CALLBACKS{$option}->(@_);
  534.     }
  535.  
  536.     return $retval;
  537. }
  538.  
  539. #-------------------------------------------------------------------------#
  540. # member functions and methods                                            #
  541. #-------------------------------------------------------------------------#
  542.  
  543. sub new {
  544.     my $class = shift;
  545.     return bless {'_CALLBACKS' => {}}, $class;
  546. }
  547.  
  548. # Add a callback for the given security option (read_file, write_file,
  549. # create_dir, read_net, write_net).
  550. #
  551. # To register a callback that handle network read requests:
  552. #   $scb->register_callback( read_net => \&callback );
  553. sub register_callback {
  554.    my $self = shift;
  555.    my $option = shift;
  556.    my $callback = shift;
  557.  
  558.    unless ( exists $OPTION_MAP{$option} ) {
  559.       croak "Invalid security option '$option'. Must be one of: " .
  560.             join(', ', keys %OPTION_MAP) . ".";
  561.    }
  562.  
  563.    if ( ref $callback eq 'CODE' ) {
  564.       $self->{_CALLBACKS}{ $OPTION_MAP{$option} } = $callback;
  565.    }
  566.    else {
  567.       croak "Invalid argument. The callback must be a reference to a subroutine";
  568.    }
  569. }
  570.  
  571. # Removes the callback for the given security option. Causes the given option
  572. # to use the default security handler (which always allows the action).
  573. sub unregister_callback {
  574.    my $self = shift;
  575.    my $option = shift;
  576.  
  577.    unless ( exists $OPTION_MAP{$option} ) {
  578.       croak "Invalid security option '$option'. Must be one of: " .
  579.             join(', ', keys %OPTION_MAP) . ".";
  580.    }
  581.  
  582.    delete $self->{_CALLBACKS}{ $OPTION_MAP{$option} };
  583. }
  584.  
  585.  
  586. # make it so libxslt can use the callbacks
  587. sub init_callbacks {
  588.     my $self = shift;
  589.  
  590.     %_GLOBAL_CALLBACKS = %{ $self->{_CALLBACKS} };
  591. }
  592.  
  593. # reset libxslt callbacks
  594. sub cleanup_callbacks {
  595.     my $self = shift;
  596.  
  597.     %_GLOBAL_CALLBACKS = ();
  598. }
  599.  
  600. 1;
  601.  
  602. __END__
  603.  
  604. =head1 NAME
  605.  
  606. XML::LibXSLT - Interface to the gnome libxslt library
  607.  
  608. =head1 SYNOPSIS
  609.  
  610.   use XML::LibXSLT;
  611.   use XML::LibXML;
  612.   
  613.   my $xslt = XML::LibXSLT->new();
  614.   
  615.   my $source = XML::LibXML->load_xml(location => 'foo.xml');
  616.   my $style_doc = XML::LibXML->load_xml(location=>'bar.xsl', no_cdata=>1);
  617.   
  618.   my $stylesheet = $xslt->parse_stylesheet($style_doc);
  619.   
  620.   my $results = $stylesheet->transform($source);
  621.   
  622.   print $stylesheet->output_as_bytes($results);
  623.  
  624. =head1 DESCRIPTION
  625.  
  626. This module is an interface to the gnome project's libxslt. This is an
  627. extremely good XSLT engine, highly compliant and also very fast. I have
  628. tests showing this to be more than twice as fast as Sablotron.
  629.  
  630. =head1 OPTIONS
  631.  
  632. XML::LibXSLT has some global options. Note that these are probably not
  633. thread or even fork safe - so only set them once per process. Each one
  634. of these options can be called either as class methods, or as instance
  635. methods. However either way you call them, it still sets global options.
  636.  
  637. Each of the option methods returns its previous value, and can be called
  638. without a parameter to retrieve the current value.
  639.  
  640. =over
  641.  
  642. =item max_depth
  643.  
  644.   XML::LibXSLT->max_depth(1000);
  645.  
  646. This option sets the maximum recursion depth for a stylesheet. See the
  647. very end of section 5.4 of the XSLT specification for more details on
  648. recursion and detecting it. If your stylesheet or XML file requires
  649. seriously deep recursion, this is the way to set it. Default value is
  650. 250.
  651.  
  652. =item debug_callback
  653.  
  654.   XML::LibXSLT->debug_callback($subref);
  655.  
  656. Sets a callback to be used for debug messages. If you don't set this,
  657. debug messages will be ignored.
  658.  
  659. =item register_function
  660.  
  661.   XML::LibXSLT->register_function($uri, $name, $subref);
  662.  
  663. Registers an XSLT extension function mapped to the given URI. For example:
  664.  
  665.   XML::LibXSLT->register_function("urn:foo", "bar",
  666.     sub { scalar localtime });
  667.  
  668. Will register a C<bar> function in the C<urn:foo> namespace (which you
  669. have to define in your XSLT using C<xmlns:...>) that will return the
  670. current date and time as a string:
  671.  
  672.   <xsl:stylesheet version="1.0"
  673.     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  674.     xmlns:foo="urn:foo">
  675.   <xsl:template match="/">
  676.     The time is: <xsl:value-of select="foo:bar()"/>
  677.   </xsl:template>
  678.   </xsl:stylesheet>
  679.  
  680. Parameters can be in whatever format you like. If you pass in a nodelist
  681. it will be a XML::LibXML::NodeList object in your perl code, but ordinary
  682. values (strings, numbers and booleans) will be ordinary perl scalars. If
  683. you wish them to be C<XML::LibXML::Literal>, C<XML::LibXML::Number> and
  684. C<XML::LibXML::Number> values respectively then set the variable
  685. C<$XML::LibXSLT::USE_LIBXML_DATA_TYPES> to a true value. Return values can
  686. be a nodelist or a plain value - the code will just do the right thing.
  687. But only a single return value is supported (a list is not converted to
  688. a nodelist).
  689.  
  690. =back
  691.  
  692. =head1 API
  693.  
  694. The following methods are available on the new XML::LibXSLT object:
  695.  
  696. =over
  697.  
  698. =item parse_stylesheet($stylesheet_doc)
  699.  
  700. C<$stylesheet_doc> here is an XML::LibXML::Document object (see L<XML::LibXML>)
  701. representing an XSLT file. This method will return a 
  702. XML::LibXSLT::Stylesheet object, or undef on failure. If the XSLT is
  703. invalid, an exception will be thrown, so wrap the call to 
  704. parse_stylesheet in an eval{} block to trap this.
  705.  
  706. IMPORTANT: C<$stylesheet_doc> should not contain CDATA sections,
  707. otherwise libxslt may misbehave. The best way to assure this is to
  708. load the stylesheet with no_cdata flag, e.g.
  709.  
  710.   my $stylesheet_doc = XML::LibXML->load_xml(location=>"some.xsl", no_cdata=>1);
  711.  
  712. =item parse_stylesheet_file($filename)
  713.  
  714. Exactly the same as the above, but parses the given filename directly.
  715.  
  716. =back
  717.  
  718. =head1 Input Callbacks
  719.  
  720. To define XML::LibXSLT or XML::LibXSLT::Stylesheet specific input
  721. callbacks, reuse the XML::LibXML input callback API as described in
  722. L<XML::LibXML::InputCallback(3)>.
  723.  
  724. =head1 Security Callbacks
  725.  
  726. To create security preferences for the transformation see
  727. L<XML::LibXSLT::Security>. Once the security preferences have been defined you
  728. can apply them to an XML::LibXSLT or XML::LibXSLT::Stylesheet instance using
  729. the C<security_callbacks()> method.
  730.  
  731. =head1 XML::LibXSLT::Stylesheet
  732.  
  733. The main API is on the stylesheet, though it is fairly minimal.
  734.  
  735. One of the main advantages of XML::LibXSLT is that you have a generic
  736. stylesheet object which you call the transform() method passing in a
  737. document to transform. This allows you to have multiple transformations
  738. happen with one stylesheet without requiring a reparse.
  739.  
  740. =over
  741.  
  742. =item transform(doc, %params)
  743.  
  744.   my $results = $stylesheet->transform($doc, foo => "value);
  745.   print $stylesheet->output_as_bytes($results);
  746.  
  747. Transforms the passed in XML::LibXML::Document object, and returns a
  748. new XML::LibXML::Document. Extra hash entries are used as parameters.
  749. See output_string
  750.  
  751. =item transform_file(filename, %params)
  752.  
  753.   my $results = $stylesheet->transform_file($filename, bar => "value");
  754.  
  755. =item output_as_bytes(result)
  756.  
  757. Returns a scalar that is the XSLT rendering of the
  758. XML::LibXML::Document object using the desired output format
  759. (specified in the xsl:output tag in the stylesheet). Note that you can
  760. also call $result->toString, but that will *always* output the
  761. document in XML format which may not be what you asked for in the
  762. xsl:output tag. The scalar is a byte string encoded in the output
  763. encoding specified in the stylesheet.
  764.  
  765. =item output_as_chars(result)
  766.  
  767. Like C<output_as_bytes(result)>, but always return the output as (UTF-8
  768. encoded) string of characters.
  769.  
  770. =item output_string(result)
  771.  
  772. DEPRECATED: This method is something between
  773. C<output_as_bytes(result)> and C<output_as_bytes(result)>: The scalar
  774. returned by this function appears to Perl as characters (UTF8 flag is
  775. on) if the output encoding specified in the XSLT stylesheet was UTF-8
  776. and as bytes if no output encoding was specified or if the output
  777. encoding was other than UTF-8. Since the behavior of this function
  778. depends on the particular stylesheet, it is deprecated in favor of
  779. C<output_as_bytes(result)> and C<output_as_chars(result)>.
  780.  
  781. =item output_fh(result, fh)
  782.  
  783. Outputs the result to the filehandle given in C<$fh>.
  784.  
  785. =item output_file(result, filename)
  786.  
  787. Outputs the result to the file named in C<$filename>.
  788.  
  789. =item output_encoding()
  790.  
  791. Returns the output encoding of the results. Defaults to "UTF-8".
  792.  
  793. =item media_type()
  794.  
  795. Returns the output media_type of the results. Defaults to "text/html".
  796.  
  797. =back
  798.  
  799. =head1 Parameters
  800.  
  801. LibXSLT expects parameters in XPath format. That is, if you wish to pass
  802. a string to the XSLT engine, you actually have to pass it as a quoted
  803. string:
  804.  
  805.   $stylesheet->transform($doc, param => "'string'");
  806.  
  807. Note the quotes within quotes there!
  808.  
  809. Obviously this isn't much fun, so you can make it easy on yourself:
  810.  
  811.   $stylesheet->transform($doc, XML::LibXSLT::xpath_to_string(
  812.         param => "string"
  813.         ));
  814.  
  815. The utility function does the right thing with respect to strings in XPath,
  816. including when you have quotes already embedded within your string.
  817.  
  818.  
  819. =head1 XML::LibXSLT::Security
  820.  
  821. Provides an interface to the libxslt security framework by allowing callbacks
  822. to be defined that can restrict access to various resources (files or URLs)
  823. during a transformation.
  824.  
  825. The libxslt security framework allows callbacks to be defined for certain
  826. actions that a stylesheet may attempt during a transformation. It may be
  827. desirable to restrict some of these actions (for example, writing a new file
  828. using exsl:document). The actions that may be restricted are:
  829.  
  830. =over
  831.  
  832. =item read_file
  833.  
  834. Called when the stylesheet attempts to open a local file (ie: when using the
  835. document() function).
  836.  
  837. =item write_file
  838.  
  839. Called when an attempt is made to write a local file (ie: when using the
  840. exsl:document element).
  841.  
  842. =item create_dir
  843.  
  844. Called when a directory needs to be created in order to write a file.
  845.  
  846. NOTE: By default, create_dir is not allowed. To enable it a callback must be
  847. registered.
  848.  
  849. =item read_net
  850.  
  851. Called when the stylesheet attempts to read from the network.
  852.  
  853. =item write_net
  854.  
  855. Called when the stylesheet attempts to write to the network.
  856.  
  857. =back
  858.  
  859. =head2 Using XML::LibXSLT::Security
  860.  
  861. The interface for this module is similar to XML::LibXML::InputCallback. After
  862. creating a new instance you may register callbacks for each of the security
  863. options listed above. Then you apply the security preferences to the
  864. XML::LibXSLT or XML::LibXSLT::Stylesheet object using C<security_callbacks()>.
  865.  
  866.   my $security = XML::LibXSLT::Security->new();
  867.   $security->register_callback( read_file  => $read_cb );
  868.   $security->register_callback( write_file => $write_cb );
  869.   $security->register_callback( create_dir => $create_cb );
  870.   $security->register_callback( read_net   => $read_net_cb );
  871.   $security->register_callback( write_net  => $write_net_cb );
  872.  
  873.   $xslt->security_callbacks( $security );
  874.    -OR-
  875.   $stylesheet->security_callbacks( $security );
  876.  
  877.  
  878. The registered callback functions are called when access to a resource is
  879. requested. If the access should be allowed the callback should return 1, if
  880. not it should return 0. The callback functions should accept the following
  881. arguments:
  882.  
  883. =over
  884.  
  885. =item $tctxt
  886.  
  887. This is the transform context (XML::LibXSLT::TransformContext). You can use
  888. this to get the current XML::LibXSLT::Stylesheet object by calling
  889. C<stylesheet()>.
  890.  
  891.   my $stylesheet = $tctxt->stylesheet();
  892.  
  893. The stylesheet object can then be used to share contextual information between
  894. different calls to the security callbacks.
  895.  
  896. =item $value
  897.  
  898. This is the name of the resource (file or URI) that has been requested.
  899.  
  900. =back
  901.  
  902. If a particular option (except for C<create_dir>) doesn't have a registered
  903. callback, then the stylesheet will have full access for that action.
  904.  
  905. =head2 Interface
  906.  
  907. =over
  908.  
  909. =item new()
  910.  
  911. Creates a new XML::LibXSLT::Security object.
  912.  
  913. =item register_callback( $option, $callback )
  914.  
  915. Registers a callback function for the given security option (listed above).
  916.  
  917. =item unregister_callback( $option )
  918.  
  919. Removes the callback for the given option. This has the effect of allowing all
  920. access for the given option (except for C<create_dir>).
  921.  
  922. =back
  923.  
  924. =head1 BENCHMARK
  925.  
  926. Included in the distribution is a simple benchmark script, which has two
  927. drivers - one for LibXSLT and one for Sablotron. The benchmark requires
  928. the testcases files from the XSLTMark distribution which you can find
  929. at http://www.datapower.com/XSLTMark/
  930.  
  931. Put the testcases directory in the directory created by this distribution,
  932. and then run:
  933.  
  934.   perl benchmark.pl -h
  935.  
  936. to get a list of options.
  937.  
  938. The benchmark requires XML::XPath at the moment, but I hope to factor that
  939. out of the equation fairly soon. It also requires Time::HiRes, which I
  940. could be persuaded to factor out, replacing it with Benchmark.pm, but I
  941. haven't done so yet.
  942.  
  943. I would love to get drivers for XML::XSLT and XML::Transformiix, if you
  944. would like to contribute them. Also if you get this running on Win32, I'd
  945. love to get a driver for MSXSLT via OLE, to see what we can do against
  946. those Redmond boys!
  947.  
  948. =head1 LIBRARY VERSIONS
  949.  
  950. For debugging purposes, XML::LibXSLT provides version information
  951. about the libxslt C library (but do not confuse it with the version
  952. number of XML::LibXSLT module itself, i.e. with
  953. C<$XML::LibXSLT::VERSION>). XML::LibXSLT issues a warning if the
  954. runtime version of the library is less then the compile-time version.
  955.  
  956. =over 
  957.  
  958. =item XML::LibXSLT::LIBXSLT_VERSION()
  959.  
  960. Returns version number of libxslt library which was used to compile
  961. XML::LibXSLT as an integer. For example, for libxslt-1.1.18, it will
  962. return 10118.
  963.  
  964. =item XML::LibXSLT::LIBXSLT_DOTTED_VERSION()
  965.  
  966. Returns version number of libxslt library which was used to compile
  967. XML::LibXSLT as a string, e.g. "1.1.18".
  968.  
  969. =item XML::LibXSLT::LIBXSLT_RUNTIME_VERSION()
  970.  
  971. Returns version number of libxslt library to which XML::LibXSLT is
  972. linked at runtime (either dynamically or statically). For example, for
  973. example, for libxslt.so.1.1.18, it will return 10118.
  974.  
  975. =item XML::LibXSLT::HAVE_EXLT()
  976.  
  977. Returns 1 if the module was compiled with libexslt, 0 otherwised.
  978.  
  979. =back
  980.  
  981. =head1 LICENSE
  982.  
  983. This is free software, you may use it and distribute it under the same terms as
  984. Perl itself.
  985.  
  986. Copyright 2001-2009, AxKit.com Ltd.
  987.  
  988. =head1 AUTHOR
  989.  
  990. Matt Sergeant, matt@sergeant.org
  991.  
  992. Security callbacks implementation contributed by Shane Corgatelli.
  993.  
  994. =head1 MAINTAINER
  995.  
  996. Petr Pajas , pajas@matfyz.org
  997.  
  998. =head1 BUGS
  999.  
  1000. Please report bugs via
  1001.  
  1002.   http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXSLT
  1003.  
  1004. =head1 SEE ALSO
  1005.  
  1006. XML::LibXML
  1007.  
  1008. =cut
  1009.